PIC24F
RTCC Module Library Help
Table Of Contents
2 Using Library Functions in Your Code
This peripheral library module:
· Provides a Real-Time Clock and Calendar (RTCC) function.
· Is intended for applications where accurate time must be maintained for extended periods of time with minimum to no intervention from the CPU.
· Is optimized for low-power usage in order to provide extended battery lifetime while keeping track of time.
Library routine parameters can be constructed using either AND based mask or AND_OR based mask setting. For more information on these masks, see 16-bit Peripheral Libraries.
Example of Use
#include “rtcc.h”
rtccTime RtccTime; /* Initialize time struct with required values */
rtccTime RtccTimeVal; /* Initialize time struct with required values */
BOOL update_time;
BOOL update_alarm;
BOOL Time_Input_out_of_range;
void main(void)
{
RtccInitClock(); //turn on clock source
RtccWrOn(); //enable RTCC peripheral
while(1)
{
/* Update the Time if requested */
if(update_time)
{
Time_Input_out_of_range = (!RtccWriteTime(&RtccTime, TRUE));
update_time = 0;
}
RtccReadTime(&RtccTimeVal);
/*
Supporting Application function / Code
*/
}//end RTCCModule
Function Prototype |
void RtccInitClock(void); |
Include |
rtcc.h |
Description |
The function initializes the RTCC device. It starts the RTCC clock, sets the RTCC Off and disables RTCC write. Disables the OE. |
Arguments |
None |
Return Value |
None |
Remarks: |
None |
Source File: |
RtccInitClock.c |
Function Prototype |
void RtccReadAlrmDate (rtccDate* pDt); |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current alarm Date of the RTCC device. |
Arguments |
pDt - pointer to a rtccDate union to store the alarm Date (rtccDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
pDt must be a valid pointer. |
Source File: |
RtccReadAlrmDate.c |
Function Prototype |
void RtccReadAlrmTime (rtccTime* pTm); |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current alarm time of the RTCC device. |
Arguments |
pTm - pointer to a rtccTime union to store the alarm time (rtccTime data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
pTm must be a valid pointer. |
Source File: |
RtccReadAlrmTime.c |
Function Prototype |
void RtccReadAlrmTimeDate(rtccTimeDate* pTD); |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current alarm time and date of the RTCC device. |
Arguments |
pTD - pointer to a rtccTimeDate union to store the alarm time and date (rtccTimeDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
pTD must be a valid pointer. |
Source File: |
RtccReadAlrmTimeDate.c |
Function Prototype |
void RtccReadDate(rtccDate* pDt); |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time of the RTCC device. |
Arguments |
pDt - pointer to a rtccDate union to store the current time (rtccDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
The function makes sure that the read value is valid. It avoids waiting for the RTCSYNC to be clear by performing successive reads. |
Source File: |
RtccReadDate.c |
Function Prototype |
void RtccReadTime(rtccTime* pTm); |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time of the RTCC device. |
Arguments |
pTm - pointer to a rtccTime union to store the current time (rtccTime data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
The function makes sure that the read value is valid. It avoids waiting for the RTCSYNC to be clear by performing successive reads. |
Source File: |
RtccReadTime.c |
Function Prototype |
void RtccReadTimeDate(rtccTimeDate* pTD) |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time and date of the RTCC device. |
Arguments |
pTD - pointer to a rtccTimeDate union to store the current time and date (rtccTimeDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
This firmware solution would consist of reading each register twice and then comparing the two values. If the two values match, then a rollover did not occur. |
Source File: |
RtccReadTimeDate.c |
Function Prototype |
void RtccSetAlarmRpt(rtccRepeat rpt, BOOL dsblAlrm) |
Include |
rtcc.h |
Description |
The function sets the RTCC alarm repeat rate. rpt has to be a proper rtccRepeat enumeration value. |
Arguments |
rpt - value of the desired alarm repeat rate. dsblAlrm - if TRUE, the API can temporarily disable the alarm when changing the RPT value. |
Return Value |
None |
Remarks: |
If alarm is enabled, changing the repeat rate can be safely made only when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has the knowledge that an alarm event is not imminent. |
Source File: |
RtccSetAlarmRpt.c |
Function Prototype |
void RtccSetAlarmRptCount(int rptCnt, BOOL dsblAlrm) |
Include |
rtcc.h |
Description |
The function sets the RTCC alarm repeat rate. rpt has to be a proper rtccRepeat enumeration value. |
Arguments |
rptCnt - value of the desired alarm repeat count (has to be a value less then 255). dsblAlrm - if TRUE, the API can temporarily disable the alarm when changing the RPT value. |
Return Value |
None |
Remarks: |
If alarm is enabled, changing the repeat count can be safely made only when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has the knowledge that an alarm event is not imminent. |
Source File: |
RtccSetAlarmRptCount.c |
Function Prototype |
void RtccSetCalibration(int drift) |
Include |
rtcc.h |
Description |
The function updates the value that the RTCC uses in the auto-adjust feature, once every minute. The drift value acts as a signed value, [-128*4, +127*4], 0 not having any effect. |
Arguments |
drift - value to be added/subtracted to perform calibration drift has to fit into signed 8 bits representation |
Return Value |
None |
Remarks: |
Writes to the RCFGCAL.CAL[7:0] register should only occur when the timer is turned off or immediately or after the edge of the seconds pulse (except when SECONDS=00 - due to the possibility of the auto-adjust event). In order to speed-up the process, the API function performs the reading of the HALFSEC field. The function may block for half a second, worst case, when called at the start of the minute. Interrupts can not be disabled for such a long period. However, long interrupt routines can interfere with the proper functioning of the device. Care must be taken. |
Source File: |
RtccSetCalibration.c |
Function Prototype |
void RtccSetChimeEnable(BOOL enable, BOOL dsblAlrm) |
Include |
rtcc.h |
Description |
The function enables/disables the chime alarm of the RTCC device. |
Arguments |
enable - boolean to enable/disable the RTCC chime. dsblAlrm - if TRUE, the API can temporarily disable the alarm when changing the Chime status. |
Return Value |
None |
Remarks: |
If alarm is enabled, changing the chime status can be safely made when the sync pulse is unasserted. To avoid waiting for the sync pulse, the user can choose to temporarily disable the alarm and then re-enable it. This means that the user has knowledge that an alarm event is not imminent. |
Source File: |
RtccSetChimeEnable.c |
Function Prototype |
void RtccWriteAlrmDate(const rtccDate* pDt) |
Include |
rtcc.h |
Description |
The function sets the alarm date in the RTCC device. |
Arguments |
pDt - pointer to a constant rtccDate union (rtccDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
pDt a valid rtccDate pointer having proper values: - wday: BCD codification, 00-06 - mday: BCD codification, 01-31 - mon : BCD codification, 01-12 The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled in order to safely perform the update of the ALRMTIME register. However, the device status will be restored. Note that the alarm date does not contain a year field. |
Source File: |
RtccWriteAlrmDate.c |
Function Prototype |
void RtccWriteAlrmTime(const rtccTime* pTm) |
Include |
rtcc.h |
Description |
This function sets the current time in the RTCC device. |
Arguments |
pTm - pointer to a constant rtccTime union (rtccTime data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
pTm a valid rtccTime pointer having proper values: - sec : BCD codification, 00-59 - min : BCD codification, 00-59 - hour: BCD codification, 00-24 The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. |
Source File: |
RtccWriteAlrmTime.c |
Function Prototype |
void RtccWrOn(void) |
Include |
rtcc.h |
Description |
Function to set the RCFGCAL.RTCWREN bitfield. |
Arguments |
None |
Return Value |
None |
Remarks: |
The interrupts are disabled in order to have a proper device initialization |
Source File: |
RtccWrOn.c |
Function Prototype |
void RtccWriteAlrmTimeDate(const rtccTimeDate* pTD) |
Include |
rtcc.h |
Description |
The function sets the current alarm time and date in the RTCC device. |
Arguments |
pTD - pointer to a constant rtccTimeDate union (rtccTimeDate data type is defined in rtcc.h.) |
Return Value |
None |
Remarks: |
rtccTimeDate structure fields have to have proper values: - sec : BCD codification, 00-59 - min : BCD codification, 00-59 - hour: BCD codification, 00-24 - wday: BCD codification, 00-06 - mday: BCD codification, 01-31 - mon : BCD codification, 01-12 Note that the alarm time does not contain a year field. |
Source File: |
RtccWriteAlrmTimeDate.c |
Function Prototype |
BOOL RtccWriteDate(const rtccDate* pDt, BOOL di) |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time and date of the RTCC device. |
Arguments |
pDt - pointer to a constant rtccDate union (rtccDate data type is defined in rtcc.h.) di - if interrupts need to be disabled. |
Return Value |
TRUE '1' : If all the values are within range. FALSE '0' : If any value is out of above mentioned range. |
Remarks: |
pDt is a valid rtccDate pointer having proper values: - wday: BCD codification, 00-06 - mday: BCD codification, 01-31 - mon : BCD codification, 01-12 - year: BCD codification, 00-99 The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored. Usually the disabling of the interrupts is desired, if the user has to have more precise control over the actual moment of the time setting. |
Source File: |
RtccWriteDate.c |
Function Prototype |
BOOL RtccWriteTime(const rtccTime* pTm, BOOL di) |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time and date of the RTCC device. |
Arguments |
pTm - pointer to a constant rtccTime union (rtccTime data type is defined in rtcc.h.) di - if interrupts need to be disabled. |
Return Value |
TRUE '1' : If all the values are within range. FALSE '0' : If any value is out of above mentioned range. |
Remarks: |
pTm pointing to a valid rtccTime structure having proper values: - sec : BCD codification, 00-59 - min : BCD codification, 00-59 - hour: BCD codification, 00-24 The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored. Usually the disabling of the interrupts is desired, if the user has to have more precise control over the actual moment of the time setting. |
Source File: |
RtccWriteTime.c |
Function Prototype |
BOOL RtccWriteTimeDate(const rtccTimeDate* pTD) |
Include |
rtcc.h |
Description |
The function updates the user supplied union/structure with the current time and date of the RTCC device. |
Arguments |
pTD - pointer to a rtccTimeDate union to store the current time and date (rtccTimeDate data type is defined in rtcc.h.) di - if interrupts need to be disabled |
Return Value |
TRUE '1' : If all the values are within range. FALSE '0' : If any value is out of above mentioned range. |
Remarks: |
rtccTimeDate structure fields have to have proper values: - sec : BCD codification, 00-59 - min : BCD codification, 00-59 - hour: BCD codification, 00-24 - wday: BCD codification, 00-06 - mday: BCD codification, 01-31 - mon : BCD codification, 01-12 - year: BCD codification, 00-99 The write is successful only if Wr Enable is set. The function will enable the write itself, if needed. Also, the Alarm will be temporarily disabled and the device will be stopped (On set to 0) in order to safely perform the update of the RTC time register. However, the device status will be restored. Usually the disabling of the interrupts is desired, if the user has to have more precise control over the actual moment of the time setting. |
Source File: |
RtccWriteTimeDate.c |
Macro |
mRtccIsWrEn() |
Include |
rtcc.h |
Description |
Returns the value of RCFGCAL.RTCWREN. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccWrOff() |
Include |
rtcc.h |
Description |
Macro to to clear the RCFGCAL.RTCWREN |
Arguments |
None |
Remarks |
None |
Macro |
mRtccIsOn() |
Include |
rtcc.h |
Description |
Returns the value of RCFGCAL.RTCEN. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccOff() |
Include |
rtcc.h |
Description |
Macro to turn the RTCC off. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccOn() |
Include |
rtcc.h |
Description |
Macro helper to turn the RTCC on. |
Arguments |
None |
Remarks |
Setting RCFGCAL.RTCEN to 1 clears the RTCWREN, RTCSYNC, HALFSEC, RTCOE and the ALCFGRPT register. |
Macro |
mRtccIsAlrmEnabled() |
Include |
rtcc.h |
Description |
Returns the value of ALCFGRPT.ALRMEN |
Arguments |
None |
Remarks |
None |
Macro |
mRtccAlrmEnable() |
Include |
rtcc.h |
Description |
Macro to set the ALCFGRPT.ALRMEN. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccAlrmDisable() |
Include |
rtcc.h |
Description |
Macro to clear the ALCFGRPT.ALRMEN. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccIsSync() |
Include |
rtcc.h |
Description |
Macro read the status of the sync signal. TRUE if sync asserted, FALSE otherwise |
Arguments |
None |
Remarks |
None |
Macro |
mRtccWaitSync() |
Include |
rtcc.h |
Description |
Macro to wait until RCFGCAL.RTCSYNC signals read/write is safe. |
Arguments |
None |
Remarks |
In order to be sure that the write/read op is safe, interrupts should be disabled or kept very short (worst case scenario, sync can be asserted for 32 RTCC clocks, i.e. almost 1ms, so it is not advisable to disable the interrupts for such a long period of time. Care must be taken under these circumstances). |
Macro |
mRtccIs2ndHalfSecond() |
Include |
rtcc.h |
Description |
Reads the half-second status bit. TRUE if it's the second half period of a second; FALSE otherwise. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccClearRtcPtr() |
Include |
rtcc.h |
Description |
Clears the RTCC Value Register Window Pointer bits. |
Arguments |
None |
Remarks |
It sets the pointer to the min/sec slot. |
Macro |
mRtccSetRtcPtr(mask) |
Include |
rtcc.h |
Description |
Set the RTCC Value Register Window Pointer bits to the desired value. |
Arguments |
mask - value of the pointer mask enum RTCCPTR_MASK defined in rtcc.h. mask has to be valid member of RTCCPTR_MASK. |
Remarks |
Macro mRtccClearRtcPtr() must be called prior to this macro. |
Macro |
mRtccSetAlrmPtr() |
Include |
rtcc.h |
Description |
Macro to set the Alarm Value Register Window Pointer bits. |
Arguments |
None |
Remarks |
It sets the pointer to the slot beyond the ALRMDAY. Macro mRtccClearAlrmPtr() must be called prior to this macro. |
Macro |
mRtccClearAlrmPtr() |
Include |
rtcc.h |
Description |
Macro to clear the Alarm Value Register Window Pointer bits. |
Arguments |
None |
Remarks |
It sets the pointer to the slot beyond the ALRMDAY. |
Macro |
mRtccGetChimeEnable() |
Include |
rtcc.h |
Description |
Returns the chime alarm of the RTCC device. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccGetCalibration() |
Include |
rtcc.h |
Description |
Returns the value that the RTCC uses in the auto-adjust feature, once every minute. |
Arguments |
None |
Remarks |
The calibration value is a signed 10 bits value, [-512, +511]. |
Macro |
mRtccSetClockOe(enable) |
Include |
rtcc.h |
Description |
Enables/disables the Output Enable pin of the RTCC. |
Arguments |
enable - the desired status of the Output Enable pin. |
Remarks |
None |
Macro |
mRtccSetInt(enable) |
Include |
rtcc.h |
Description |
Enables/disables the RTCC event interrupts. |
Arguments |
enable - enable/disable the interrupt. |
Remarks |
None |
Macro |
mRtccSetIntPriority(pri) |
Include |
rtcc.h |
Description |
Sets the RTCC event interrupt priority. |
Arguments |
pri - the interrupt priority. |
Remarks |
None |
Macro |
mRtccGetAlarmRpt() |
Include |
rtcc.h |
Description |
The macro returns the current RTCC alarm repeat rate. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccGetAlarmRptCount() |
Include |
rtcc.h |
Description |
The macro reads the RTCC alarm repeat counter. |
Arguments |
None |
Remarks |
None |
Macro |
mRtccGetCalibration() |
Include |
rtcc.h |
Description |
The macro returns the value that the RTCC uses in the auto-adjust feature, once every minute. |
Arguments |
The calibration value is a signed 10 bits value, [-512, +511]. |
Remarks |
None |